home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimphelpui.sgml < prev    next >
Encoding:
SGML Document  |  2003-05-20  |  10.9 KB  |  252 lines
  1. <refentry id="libgimp-gimphelpui" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimphelpui</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimphelpui</refname><refpurpose>Functions for setting <link linkend="GtkTooltips">GtkTooltips</link> and HTML links into the GIMP help
  10. system.</refpurpose>
  11. </refnamediv>
  12.  
  13. <refsynopsisdiv><title>Synopsis</title>
  14. <synopsis>
  15.  
  16.  
  17.  
  18. void        (<link linkend="GimpHelpFunc">*GimpHelpFunc</link>)                 (const <link linkend="gchar">gchar</link> *help_data);
  19. void        <link linkend="gimp-help-init">gimp_help_init</link>                  (void);
  20. void        <link linkend="gimp-help-free">gimp_help_free</link>                  (void);
  21. void        <link linkend="gimp-help-enable-tooltips">gimp_help_enable_tooltips</link>       (void);
  22. void        <link linkend="gimp-help-disable-tooltips">gimp_help_disable_tooltips</link>      (void);
  23. void        <link linkend="gimp-standard-help-func">gimp_standard_help_func</link>         (const <link linkend="gchar">gchar</link> *help_data);
  24. void        <link linkend="gimp-help-connect-help-accel">gimp_help_connect_help_accel</link>    (<link linkend="GtkWidget">GtkWidget</link> *widget,
  25.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  26.                                              const <link linkend="gchar">gchar</link> *help_data);
  27. void        <link linkend="gimp-help-set-help-data">gimp_help_set_help_data</link>         (<link linkend="GtkWidget">GtkWidget</link> *widget,
  28.                                              const <link linkend="gchar">gchar</link> *tooltip,
  29.                                              const <link linkend="gchar">gchar</link> *help_data);
  30. void        <link linkend="gimp-context-help">gimp_context_help</link>               (void);
  31. </synopsis>
  32. </refsynopsisdiv>
  33.  
  34.  
  35.  
  36.  
  37.  
  38. <refsect1>
  39. <title>Description</title>
  40. <para>
  41.  
  42. </para>
  43. </refsect1>
  44.  
  45. <refsect1>
  46. <title>Details</title>
  47. <refsect2>
  48. <title><anchor id="GimpHelpFunc">GimpHelpFunc ()</title>
  49. <programlisting>void        (*GimpHelpFunc)                 (const <link linkend="gchar">gchar</link> *help_data);</programlisting>
  50. <para>
  51. This is the prototype for all functions you pass as <parameter>help_func</parameter> to the
  52. various GIMP dialog constructors like <link linkend="gimp-dialog-new">gimp_dialog_new</link>(),
  53. <link linkend="gimp-query-int-box">gimp_query_int_box</link>() etc.
  54. </para>
  55.  
  56. <para>
  57. Note that all help paths are relative to the root of the help system
  58. in the current language. So if your language is "C", a help path of
  59. "filters/foo_bar.html" will expand to
  60. "${gimp_data_dir}/help/C/filters/foo_bar.html".
  61. </para>
  62.  
  63. <para>
  64. All these functions finally call <link linkend="gimp-help-connect-help-accel">gimp_help_connect_help_accel</link>() which
  65. does the work of installing the "F1" accelerator.
  66. </para>
  67.  
  68. <para>
  69. In most cases it will be ok to use <link linkend="gimp-plugin-help-func">gimp_plugin_help_func</link>() which does
  70. nothing but passing the <parameter>help_data</parameter> string to <link linkend="gimp-help">gimp_help</link>(). If your
  71. plug-in needs some more sophisticated help handling you can provide
  72. your own <parameter>help_func</parameter> which has to call <link linkend="gimp-help">gimp_help</link>() to actually display
  73. the help.
  74. </para><informaltable pgwide=1 frame="none" role="params">
  75. <tgroup cols="2">
  76. <colspec colwidth="2*">
  77. <colspec colwidth="8*">
  78. <tbody>
  79. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  80. <entry>A string containing the path to a HTML page.
  81.  
  82.  
  83. </entry></row>
  84. </tbody></tgroup></informaltable></refsect2>
  85. <refsect2>
  86. <title><anchor id="gimp-help-init">gimp_help_init ()</title>
  87. <programlisting>void        gimp_help_init                  (void);</programlisting>
  88. <para>
  89. This function initializes GIMP's help system.
  90. </para>
  91. <para>
  92. Currently it only creates a <link linkend="GtkTooltips">GtkTooltips</link> object with <link linkend="gtk-tooltips-new">gtk_tooltips_new</link>()
  93. which will be used by <link linkend="gimp-help-set-help-data">gimp_help_set_help_data</link>().</para>
  94. <para>
  95.  
  96. </para></refsect2>
  97. <refsect2>
  98. <title><anchor id="gimp-help-free">gimp_help_free ()</title>
  99. <programlisting>void        gimp_help_free                  (void);</programlisting>
  100. <para>
  101. This function frees the memory used by the <link linkend="GtkTooltips">GtkTooltips</link> created by
  102. <link linkend="gimp-help-init">gimp_help_init</link>().</para>
  103. <para>
  104.  
  105. </para></refsect2>
  106. <refsect2>
  107. <title><anchor id="gimp-help-enable-tooltips">gimp_help_enable_tooltips ()</title>
  108. <programlisting>void        gimp_help_enable_tooltips       (void);</programlisting>
  109. <para>
  110. This function calls <link linkend="gtk-tooltips-enable">gtk_tooltips_enable</link>().</para>
  111. <para>
  112.  
  113. </para></refsect2>
  114. <refsect2>
  115. <title><anchor id="gimp-help-disable-tooltips">gimp_help_disable_tooltips ()</title>
  116. <programlisting>void        gimp_help_disable_tooltips      (void);</programlisting>
  117. <para>
  118. This function calls <link linkend="gtk-tooltips-disable">gtk_tooltips_disable</link>().</para>
  119. <para>
  120.  
  121. </para></refsect2>
  122. <refsect2>
  123. <title><anchor id="gimp-standard-help-func">gimp_standard_help_func ()</title>
  124. <programlisting>void        gimp_standard_help_func         (const <link linkend="gchar">gchar</link> *help_data);</programlisting>
  125. <para>
  126. This is the standard GIMP help function which does nothing but calling
  127. <link linkend="gimp-help">gimp_help</link>(). Please use <link linkend="gimp-plugin-help-func">gimp_plugin_help_func</link>() for your plug-in's
  128. help links.
  129. </para>
  130.  
  131. <para>
  132. Currently, <link linkend="gimp-standard-help-func">gimp_standard_help_func</link>() and <link linkend="gimp-plugin-help-func">gimp_plugin_help_func</link>() do
  133. exactly the same. The latter one was introduced to ensure future
  134. flexibility.
  135. </para>
  136.  
  137. <para>
  138. See <link linkend="GimpHelpFunc">GimpHelpFunc</link> for the naming conventions of HTML help files.
  139. </para><informaltable pgwide=1 frame="none" role="params">
  140. <tgroup cols="2">
  141. <colspec colwidth="2*">
  142. <colspec colwidth="8*">
  143. <tbody>
  144. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  145. <entry>A string containing the path to a HTML page.
  146.  
  147.  
  148. </entry></row>
  149. </tbody></tgroup></informaltable></refsect2>
  150. <refsect2>
  151. <title><anchor id="gimp-help-connect-help-accel">gimp_help_connect_help_accel ()</title>
  152. <programlisting>void        gimp_help_connect_help_accel    (<link linkend="GtkWidget">GtkWidget</link> *widget,
  153.                                              <link linkend="GimpHelpFunc">GimpHelpFunc</link> help_func,
  154.                                              const <link linkend="gchar">gchar</link> *help_data);</programlisting>
  155. <para>
  156. Note that this function is automatically called by all libgimp dialog
  157. constructors. You only have to call it for windows/dialogs you created
  158. "manually".
  159. </para>
  160. <para>
  161. For convenience, <link linkend="gimp-help-connect-help-accel">gimp_help_connect_help_accel</link>() calls
  162. <link linkend="gimp-dialog-set-icon">gimp_dialog_set_icon</link>() if the passed widget is a <link linkend="GtkWindow">GtkWindow</link>, so you
  163. don't have to worry about this.</para>
  164. <para>
  165.  
  166. </para><informaltable pgwide=1 frame="none" role="params">
  167. <tgroup cols="2">
  168. <colspec colwidth="2*">
  169. <colspec colwidth="8*">
  170. <tbody>
  171. <row><entry align="right"><parameter>widget</parameter> :</entry>
  172. <entry> The widget you want to connect the help accelerator for. Will
  173. be a <link linkend="GtkWindow">GtkWindow</link> in most cases.
  174. </entry></row>
  175. <row><entry align="right"><parameter>help_func</parameter> :</entry>
  176. <entry> The function which will be called if the user presses "F1".
  177. </entry></row>
  178. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  179. <entry> The data pointer which will be passed to <parameter>help_func</parameter>.
  180. </entry></row>
  181. </tbody></tgroup></informaltable></refsect2>
  182. <refsect2>
  183. <title><anchor id="gimp-help-set-help-data">gimp_help_set_help_data ()</title>
  184. <programlisting>void        gimp_help_set_help_data         (<link linkend="GtkWidget">GtkWidget</link> *widget,
  185.                                              const <link linkend="gchar">gchar</link> *tooltip,
  186.                                              const <link linkend="gchar">gchar</link> *help_data);</programlisting>
  187. <para>
  188. The reason why we don't use <link linkend="gtk-tooltips-set-tip">gtk_tooltips_set_tip</link>() is that it's
  189. impossible to set a <parameter>private_tip</parameter> (aka <parameter>help_data</parameter>) without a visible
  190. <parameter>tooltip</parameter>.
  191. </para>
  192. <para>
  193. This function can be called with <parameter>tooltip</parameter> == <link linkend="NULL-CAPS">NULL</link>. Use this feature
  194. if you want to set a HTML help link for a widget which shouldn't have
  195. a visible tooltip.
  196. </para>
  197. <para>
  198. You can e.g. set a <parameter>help_data</parameter> string to a complete HTML page for a
  199. container widget (e.g. a <link linkend="GtkBox">GtkBox</link>). For the widgets inside the box
  200. you can set HTML anchors which point inside the container widget's
  201. help page by setting <parameter>help_data</parameter> strings starting with "#".
  202. </para>
  203. <para>
  204. If the tooltips inspector (Shift + "F1") is invoked and the user
  205. clicks on one of the widgets which only contain a "#" link, the
  206. help system will automatically ascend the widget hierarchy until it
  207. finds another widget with <parameter>help_data</parameter> attached and concatenates both
  208. to a complete help path.</para>
  209. <para>
  210.  
  211. </para><informaltable pgwide=1 frame="none" role="params">
  212. <tgroup cols="2">
  213. <colspec colwidth="2*">
  214. <colspec colwidth="8*">
  215. <tbody>
  216. <row><entry align="right"><parameter>widget</parameter> :</entry>
  217. <entry> The <link linkend="GtkWidget">GtkWidget</link> you want to set a <parameter>tooltip</parameter> and/or <parameter>help_data</parameter> for.
  218. </entry></row>
  219. <row><entry align="right"><parameter>tooltip</parameter> :</entry>
  220. <entry> The text for this widget's tooltip.
  221. </entry></row>
  222. <row><entry align="right"><parameter>help_data</parameter> :</entry>
  223. <entry> The <parameter>help_data</parameter> for the <link linkend="GtkTipsQuery">GtkTipsQuery</link> tooltips inspector.
  224. </entry></row>
  225. </tbody></tgroup></informaltable></refsect2>
  226. <refsect2>
  227. <title><anchor id="gimp-context-help">gimp_context_help ()</title>
  228. <programlisting>void        gimp_context_help               (void);</programlisting>
  229. <para>
  230. This function invokes the <link linkend="GtkTipsQuery">GtkTipsQuery</link> tooltips inspector.
  231. </para>
  232. <para>
  233. The mouse cursor will turn turn into a question mark and the user can
  234. click on any widget of the application which started the inspector.
  235. </para>
  236. <para>
  237. If the widget the user clicked on has a <parameter>help_data</parameter> string attached
  238. (see <link linkend="gimp-help-set-help-data">gimp_help_set_help_data</link>()), the corresponding HTML page will
  239. be displayed. Otherwise the help system will ascend the widget hierarchy
  240. until it finds an attached <parameter>help_data</parameter> string (which should be the
  241. case at least for every window/dialog).</para>
  242. <para>
  243.  
  244. </para></refsect2>
  245.  
  246. </refsect1>
  247.  
  248.  
  249.  
  250.  
  251. </refentry>
  252.